PriorBox
=================

根据输入的特征图尺寸、步长和预设的候选框配置，逐元素计算先验框（Prior Boxes），通常用于目标检测模型。

该算子遍历特征图的每一个网格中心点，并围绕该中心点生成一系列具有不同尺寸和宽高比的候选框。生成的坐标 ``[xmin, ymin, xmax, ymax]`` 经过归一化处理。

.. math::

   cx = j + offset, \quad cy = i + offset

对于每个 ``min_sizes[k]`` ：

.. math::

   \begin{aligned}
   xmin &= (cx - \frac{min_k}{2 \cdot step_w}) / fmap_w \\
   ymin &= (cy - \frac{min_k}{2 \cdot step_h}) / fmap_h \\
   xmax &= (cx + \frac{min_k}{2 \cdot step_w}) / fmap_w \\
   ymax &= (cy + \frac{min_k}{2 \cdot step_h}) / fmap_h
   \end{aligned}

当 ``max_sizes_size > 0`` 时，额外生成尺寸为 :math:`\sqrt{min_k \cdot max_k}` 的正方形先验框。

对于每个 ``different_aspect_ratios[m]`` （不等于 1.0 时）：

.. math::

   \begin{aligned}
   box\_w &= min_k \cdot \sqrt{ratio} \\
   box\_h &= min_k / \sqrt{ratio}
   \end{aligned}

输入：
    - **min_sizes** - 定义基础先验框尺寸的浮点数数组地址。
    - **max_sizes** - 可选的浮点数数组地址，用于生成额外的正方形先验框。
    - **different_aspect_ratios** - 定义不同宽高比的浮点数数组地址。
    - **output** - 用于存储最终生成的先验框坐标的数组地址。
    - **params** - 参数数组（9个元素），包含以下内容：
        - params[0]: 特征图高度 fmap_h（int）
        - params[1]: 特征图宽度 fmap_w（int）
        - params[2]: 垂直步长 step_h 的地址（float*）
        - params[3]: 水平步长 step_w 的地址（float*）
        - params[4]: 中心点偏移量 offset 的地址（float*）
        - params[5]: min_sizes 数组长度
        - params[6]: max_sizes 数组长度
        - params[7]: different_aspect_ratios 数组长度
        - params[8]: output_size 整数变量的地址（int*），函数执行后记录写入 output 的浮点数总数
    - **core_mask(int, 可选)** - 核掩码（仅适用于共享存储版本）。

输出：
    - **output** - 生成的先验框坐标。
    - **output_size** - 写入 output 数组的浮点数总数（通过 params[8] 指向的变量返回）。

支持平台：
    ``FT78NE``
    ``MT7004``

.. note::
    - FT78NE 支持 fp32 类型。
    - MT7004 支持 fp16 和 fp32 类型。
    - 当 max_sizes_size 为 0 时，不生成额外的正方形先验框。
    - 当宽高比等于 1.0 时，跳过该宽高比对应的先验框生成。

**共享存储版本:**

.. c:function:: void fp_prior_box_s(float* min_sizes, float* max_sizes, float* different_aspect_ratios, float* output, long long* params, int core_mask)
.. c:function:: void hp_prior_box_s(float16* min_sizes, float16* max_sizes, float16* different_aspect_ratios, float16* output, long long* params, int core_mask)

**C调用示例：**

.. code-block:: c
   :linenos:
   :emphasize-lines: 38

   // MT7004 示例（共享存储多核，DDR 地址）
   #include <stdio.h>
   #include <stdlib.h>
   #include "mt7004/utils.h"

   int main() {
       float *min_sizes = (float *)0x81000000;
       float *max_sizes = (float *)0x82000000;
       float *ratios = (float *)0x83000000;
       float *output = (float *)0x84000000;
       int *output_size = (int *)0x86000000;

       int i;
       int fmap_h = 4, fmap_w = 8;
       float step_h = 2.0f, step_w = 2.0f;
       float offset = 0.5f;
       int min_sizes_size = 2;
       int max_sizes_size = 0;
       int ratios_size = 0;
       int core_mask = 0xff;

       srand(12345);
       for (i = 0; i < min_sizes_size; ++i) {
           min_sizes[i] = (float)(rand() % 3 + 1);
       }

       long long params[13];
       params[0] = (long long)fmap_h;
       params[1] = (long long)fmap_w;
       params[2] = (long long)(&step_h);
       params[3] = (long long)(&step_w);
       params[4] = (long long)(&offset);
       params[5] = (long long)min_sizes_size;
       params[6] = (long long)max_sizes_size;
       params[7] = (long long)ratios_size;
       params[8] = (long long)output_size;

       fp_prior_box_s(min_sizes, max_sizes, ratios, output, params, core_mask);

       return 0;
   }

**私有存储版本:**

.. c:function:: void fp_prior_box_p(float* min_sizes, float* max_sizes, float* different_aspect_ratios, float* output, long long* params)
.. c:function:: void hp_prior_box_p(float16* min_sizes, float16* max_sizes, float16* different_aspect_ratios, float16* output, long long* params)

**C调用示例：**

.. code-block:: c
   :linenos:
   :emphasize-lines: 37

   // MT7004 示例（私有存储单核，AM 地址）
   #include <stdio.h>
   #include <stdlib.h>
   #include "mt7004/utils.h"

   int main() {
       float *min_sizes = (float *)0x10010000;
       float *max_sizes = (float *)0x10016000;
       float *ratios = (float *)0x10020000;
       float *output = (float *)0x10030000;     // 需保证足够的 DDR/AM 空间
       int *output_size = (int *)0x10050000;

       int i;
       int fmap_h = 4, fmap_w = 8;
       float step_h = 2.0f, step_w = 2.0f;
       float offset = 0.5f;
       int min_sizes_size = 2;
       int max_sizes_size = 0;
       int ratios_size = 0;

       srand(12345);
       for (i = 0; i < min_sizes_size; ++i) {
           min_sizes[i] = (float)(rand() % 3 + 1);
       }

       long long params[13];
       params[0] = (long long)fmap_h;
       params[1] = (long long)fmap_w;
       params[2] = (long long)(&step_h);
       params[3] = (long long)(&step_w);
       params[4] = (long long)(&offset);
       params[5] = (long long)min_sizes_size;
       params[6] = (long long)max_sizes_size;
       params[7] = (long long)ratios_size;
       params[8] = (long long)output_size;

       fp_prior_box_p(min_sizes, max_sizes, ratios, output, params);

       return 0;
   }